package miitoollib;

use 5.008;
use strict;
use warnings;
use Carp;

require Exporter;
use AutoLoader;

our @ISA = qw(Exporter);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

# This allows declaration	use miitoollib ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = ( 'all' => [ qw(
	
) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

our @EXPORT = qw(
	
);

our $VERSION = '0.03';

sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.

    my $constname;
    our $AUTOLOAD;
    ($constname = $AUTOLOAD) =~ s/.*:://;
    croak "&miitoollib::constant not defined" if $constname eq 'constant';
    my ($error, $val) = constant($constname);
    if ($error) { croak $error; }
    {
	no strict 'refs';
	# Fixed between 5.005_53 and 5.005_61
#XXX	if ($] >= 5.00561) {
#XXX	    *$AUTOLOAD = sub () { $val };
#XXX	}
#XXX	else {
	    *$AUTOLOAD = sub { $val };
#XXX	}
    }
    goto &$AUTOLOAD;
}

require XSLoader;
XSLoader::load('miitoollib', $VERSION);

# Preloaded methods go here.

# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__
# Below is stub documentation for your module. You'd better edit it!

=head1 NAME

miitoollib - Perl extension for Ethernet functionality

=head1 SYNOPSIS

  use miitoollib;
  #
  # Get link level status via Miitool
  #
  $r=miitoollib::miiquery("eth0");
  if($r =~ /link ok/) {
	print "link up\n";
  }
  #
  # Get link level status via Ethtool
  #
  $r=miitoollib::ethtoolquery("eth0");
  print "Link up\n" if $r==1;
  print "Request not supported\n" if $r==2;
  print "Link down\n" if !$r;
  #
  # send out gratuitous arp for eth1:1
  #
  $=miitoollib::send_arp("eth1:1");

=head1 DESCRIPTION

The miitoollib provides just two functions - miiquery anad send_arp.
Both are low level Ethernet functions.

=head2 ethtoolquery
This takes the name of an Ethernet instance and queries the link level status.

It will return 0 if the link is down, 1 if the link is up, or 2 if the 
specified interface does not exist, or does not support the relevant IOCTL.

=head2 miiquery
This takes the name of an Ethernet instance and queries the link level status.
This provides the same functionality as <B ethtoolquery> but is more efficient.
Both are supported since <B miiquery> supports fewer cards.

On a suitable connection the information required will be similar to
the following:

  eth0: negotiated 100baseTx-FD flow-control, link ok
  
Typically it is used to determine whether the specified interface
is physically connected to the network. The speed portion of the
output will be one of the following;

  10baseT-HD
  10baseT-FD
  100baseTx-HD
  100baseTx-FD
  100baseT4
  100baseTx
  10baseT

The first part if the output (following the interface name) will be
either 'negotiated' or 'no autonegotiation' indicating whether the
speed was determined via the Ethernet connection or set manually.

The 'flow-control' portion of the output is optional - only given
if the interface currently supports flow control. 

Finally the 'link ok' indicates a physical connection, whilst 
'no link' indicates no connection present.

=head2 send_arp

The send_arp function will simply send a packet out (via the 
interface specified) known as a 'gratuitous ARP' packet. This packet
will cause any other network device on the same physical medium (i.e.
connected to the same switch or hub) to update their ARP tables for
the IP address currently in use for the specified interface.

Either a real or virtual interface can be specified - for example;

  $x=miitoollib::send_arp("eth1");
  $y=miitoollib::send_arp("eth3:2");

This functionality is only available to the "root" user. Other 
users will simply get an error. The return value of the call will
be an empty string if everything was OK otherwise an error message.

=head1 EXPORT

None by default.

=head1 SEE ALSO

A command line utility called 'mii-tool' provides this and other
features including setting the link speeds rather than just querying them.

The 'send_arp' is a slightly modified version of the file send_arp.c which
can be found in the file /sbin/cluster/tools/send_arp.c. This was written
and copyright Ugen (ugen@xonix.com) - itself based on a more general 'send_arp.c'
which was written and copyright of yuri volobuev (volobuev@t1.chem.umn.edu).

This module is typically distributed as part of the Linuxha.net clustering
product. For more information please see B<http://www.linuxha.net> .

=head1 AUTHOR

Simon Edwards, E<lt>simon.edwards@linuxha.netE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2005 by Simon Edwards, Linuxha.net

This library is basically a cut-down versoin of the net-tool utility that
was present in Redhat Fedora Core 3 and includes all associated patches.

It also contains a portion of the Ethtool code to ascertain link level
support on supported interfaces.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.5 or,
at your option, any later version of Perl 5 you may have available.

=cut
